package com.example.service;

import java.util.List;
import java.util.Map;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.dto.ApiResponse;
import com.example.dto.ClassRequest;
import com.example.dto.ClassStudentDTO;
import com.example.dto.InviteCodeResponse;
import com.example.entity.Class;

public interface ClassService {
    
    /**
     * 获取系统中所有班级列表
     * @return 包含所有班级的列表，若无班级则返回空列表
     */
    List<Class> getAllClasses();

    /**
     * 获取指定教师的所有授课班级列表
     *
     * @param teacherId 教师的ID
     * @return 包含指定教师授课班级列表的List，如果没有找到对应的班级列表，则返回空列表
     */
    List<Class> getTeacherClasses(Long teacherId);

    /**
     * 根据学生ID获取该学生所在的班级列表
     *
     * @param studentId 学生ID
     * @return 学生所在的班级列表
     */
    List<Class> getStudentClasses(Long studentId);

    /**
     * 根据ID获取班级详情
     * @param id 班级ID
     * @return 对应的班级对象，若不存在返回null
     */
    Class getClassById(Long id);
    
    /**
     * 创建新班级
     * @param classRequest 班级创建请求对象
     * @param teacherId 创建者教师ID
     * @return 操作结果，包含成功信息和创建的班级对象
     */
    ApiResponse<?> createClass(ClassRequest classRequest, Long teacherId);

    /**
     * 更新班级信息
     * @param id 要更新的班级ID
     * @param classRequest 班级更新请求对象
     * @param teacherId 操作者教师ID
     * @return 操作结果，包含成功信息和更新后的班级对象
     */
    ApiResponse<?> updateClass(Long id, ClassRequest classRequest, Long teacherId);

    /**
     * 删除班级
     * @param id 要删除的班级ID
     * @param teacherId 操作者教师ID
     * @return 操作结果
     */
    ApiResponse<?> deleteClass(Long id, Long teacherId);
    
    /**
     * 生成班级邀请码
     * @param classId 班级ID
     * @param teacherId 操作者教师ID
     * @return 邀请码响应对象，包含邀请码和过期时间
     * @throws RuntimeException 当班级不存在或教师无权限时抛出
     */
    InviteCodeResponse generateInviteCode(Long classId, Long teacherId);

    /**
     * 通过邀请码加入班级
     * @param inviteCode 邀请码
     * @param studentId 学生ID
     * @return 操作结果
     */
    ApiResponse<?> joinClassByInviteCode(String inviteCode, Long studentId);
    
    /**
     * 分页查询班级学生列表
     *
     * @param classId 班级ID
     * @param page    页码
     * @param size    每页大小
     * @param query   查询条件(学生姓名)
     * @return 分页结果
     */
    Page<ClassStudentDTO> getClassStudents(Long classId, Integer page, Integer size, String query);

    /**
     * 教师手动添加学生到班级
     * @param classId 班级ID
     * @param studentId 学生ID
     * @param teacherId 操作者教师ID
     * @return 操作结果
     */
    ApiResponse<?> addStudentToClass(Long classId, Long studentId, Long teacherId);

    /**
     * 从班级移除学生
     * @param classId 班级ID
     * @param studentId 学生ID
     * @param teacherId 操作者教师ID
     * @return 操作结果
     */
    ApiResponse<?> removeStudentFromClass(Long classId, Long studentId, Long teacherId);
    
    /**
     * 获取班级统计信息
     * @param classId 班级ID
     * @return 统计信息Map，包含学生数量等信息
     * @throws RuntimeException 当班级不存在时抛出
     */
    Map<String, Object> getClassStatistics(Long classId);
} 